QuickTime 4 Reference

Preparing the Decompression Sequence

Because the effect is directly executed, the effect description is not added to a video track, as described in "Adding the Effect Description to the Track" . Instead, a decompression sequence is created to execute the effect. The sample, and its description, form part of the input to the decompression sequence. For complete details of setting up and using decompression sequences, see Chapter 4, "Image Compressor Components."

The code shown in Listing 9 prepares a decompression sequence for playback, given the effect description in myEffectDesc and the sample description in mySampleDesc . The function generates a sequence identifier, which in this example is stored in the variable gEffectSequenceID . The variable mainWindow contains the display surface on which the effect is shown. In this case, it is the application's main window. Full details of this call are provided in Chapter 3, "Image Compression Manager."

Listing 9 Preparing a decompression sequence used to execute an effect directly



 
HLock((Handle) myEffectDescription);



DecompressSequenceBeginS(&gEffectSequenceID,

                    mySampleDescription,

                    StripAddress(*myEffectDescription),

                    GetHandleSize(myEffectDescription),

                    (CGrafPtr) mainWindow,

                    nil,

                    nil,

                    nil,

                    ditherCopy,

                    nil,

                    0,

                    codecNormalQuality,

                    nil);



HUnlock((Handle) myEffectDescription);

The value passed in the accuracy parameter of this call (in this example the value is codecNormalQuality ) controls how the effect component optimizes the rendering of the effect. Values less than or equal to codecNormalQuality indicate that the visual quality of the effect may be compromised in order to achieve high-speed playback.

A setting of codecHighQuality indicates that the component should not attempt to sacrifice rendering quality for speed of playback, but should instead render the effect with maximum visual quality. This is particularly useful when the effect is being used to process images offline.

Adding Sources to the Decompression Sequence

Once the decompression sequence is set up, the sources for the effect must be associated with the source names used in the effect description. When you are creating a QuickTime movie containing effects, the input map provides this association. When an effect is being directly executed, use the functions CDSequenceNewDataSource and CDSequenceSetSourceData to create the named sources.

The code in Listing 10 shows how image descriptions for a graphics world (gWorld1 ) are generated by calling MakeImageDescriptionForPixMap . The image description is then named srcA using the CDSequenceNewDataSource function.

Listing 10 Generating image descriptions for a graphics world



 
{

    ImageSequenceDataSource     mySrc1 = 0;



    // Generate a description of the first graphics world and store it in

    // gWorld1Desc

    myErr = MakeImageDescriptionForPixMap(gWorld1->portPixMap,

                                            &gWorld1Desc);



    // Create a source from the graphics world description.

    myErr = CDSequenceNewDataSource(gEffectSequenceID,

                                &mySrc1,

                                'srcA',

                                1,

                                (Handle)gWorld1Desc,

                                nil,

                                0);



    // Set the data for source srcA to be the pixMap of the graphics

    // world gWorld1

    CDSequenceSetSourceData(mySrc1,

                        GetPixBaseAddr(gWorld1->portPixMap),

                        (**gWorld1Desc).dataSize);

}

Adding a Time Base to the Decompression Sequence

The last step in preparing the decompression sequence is creating a time base to be used in the playback of the effect.

The code in Listing 11 creates a new time base and sets its rate to 0 . The new time base is then associated with the newly created decompression sequence.

Listing 11 Adding a time base to a decompression sequence



 
gTimeBase = NewTimeBase();

SetTimeBaseRate(gTimeBase, 0);

CDSequenceSetTimeBase(gEffectSequenceID, gTimeBase);

The time base's rate is set to 0 because the effect is being played outside the context of a QuickTime movie. This means your application must repeatedly call the RunEffect function (as shown in the following code samples) to play the effect.